Overview 

The Bean Component is a pluggable container in SwitchYard which allows Java classes (or beans) to provide and consume services. This means that you can implement a service by simply annotating a Java class. It also means you can consume a service by injecting a reference to that service directly into your Java class. Rather than writing our own POJO container to provide this capability, we have implemented the bean component as a Weld extension. No need to learn a new programming model - bean services are standard CDI beans with a few extra annotations. This also opens up the possibilities of how SwitchYard is used; you can now expose existing CDI-based beans in your application as services to the outside world or consume services within your bean

Creating a Bean Service

To create a new Bean service you only need a few pieces of information:

• Name : the name of the Java class for your bean service.

• Service Name : the name of the service your bean will provide.

• Interface : the contract for the service being provided.  Java is the only valid interface type for bean services.

Note that starting with the interface value will default the names for Name and Service Name, which can speed things up if you're in a hurry.

After clicking Finish, you will have a new class that looks something like this:

package com.example.switchyard.docs;

import org.switchyard.component.bean.Service;

@Service(Example.class)
public class ExampleBean implements Example {

}

The @Service annotation allows the SwitchYard CDI Extension to discover your bean at runtime and register it as a service.  The value of the annotation (Example.class in the above example) represents the service contract for the service.  Every bean service must have an @Service annotation with a value identifying the service interface for the service.

To complete the definition of your service, add one or more operations to the service interface and provide a corresponding implementation in your bean:

package com.example.switchyard.docs;

import org.switchyard.component.bean.Service;

@Service(Example.class)
public class ExampleBean implements Example {

   public void greet(Person person) {
       // implement service logic here for greet operation
   }
}

Consuming a Service

In addition to providing a service in SwitchYard, beans can also consume other services.  These services can be provided in the same application by other implementations, or they could be wired to gateway bindings to invoke services over JMS, SOAP, FTP, etc.  The SwitchYard runtime handles the resolution of the service reference to a concrete service, allowing your service logic to remain blissfully ignorant. Invocations made through this reference are routed through the SwitchYard exchange mechanism.

Consuming a SwitchYard service from within a CDI bean is done via @Reference annotations.

@Service(ConsumerService.class)
public class ConsumerServiceBean implements ConsumerService {

   @Inject
   @Reference
   private SimpleService service;

   public void consumeSomeService(String consumerName) {
      service.sayHello("Hello " + consumerName);
   }
}

By default, SwitchYard expects a service reference to be declared with a name which matches the Java type used for the reference.  In the above example, the SimpleService type would require a service reference in your SwitchYard configuration called "SimpleService".  In the event where the service reference name is different from the type name of the contract, the @Reference annotation can accept a service name:

@Reference("urn:myservices:purchasing:OrderService")
private OrderService orders;

Invocation Properties

@Service(SimpleService.class)
public class SimpleServiceBean implements SimpleService {

@Inject
private Context context;

public String sayHello(String message) {
        System.out.println("*** Funky Context Property Value: " + context.getPropertyValue("funkyContextProperty"));
        return "Hi there!!";
    }
}

Implementation Properties

@Service(SimpleService.class)
public class SimpleServiceBean implements SimpleService {

@Property(name="user.name")
private String name;

public String sayHello(String message) {
        return "Hello " + name + ", I got a message: " + message;
    }
}

Overview

Camel services allow you to leverage the core routing engine inside of Apache Camel to route between services in SwitchYard.  All of the EIP and core routing support in Camel is available to your service implementation.  Each Camel route is exposed as a service within SwitchYard, which means it has a well-defined contract and can be injected into any other service in the runtime.

Creating a Camel Service

The first thing you need to decide when you create a Camel routing service is whether you want to use the Java DSL or XML dialect for the route.  Functionally, they are more or less equivalent, so it's more a choice of how you want to express your routing logic.  If you want create a Java DSL route, select the "Camel (Java)" implementation type.  For XML, use the "Camel (XML)" type.  Regardless of which language you choose, the following information is required:

• Name : the name of the Java class or XML file for your bean service.

• Service Name : the name of the service your bean will provide.

• Interface : the contract for the service being provided.  Camel supports Java, WSDL, and ESB contract types.

For details on each type of Camel route, see the Java DSL Routes and XML Routes sections below.  You can have multiple routing services per application, each with it's own routing language (e.g. an application can have two Java DSL routes and one XML route).  There are some general guidelines to keep in mind with both types of routes:

• There is only one route per service. 

• The consumer or "from" endpoint in a route is always a "switchyard" endpoint and the endpoint name must equal the service name.  This is default behavior in the tooling.

• To consume other services from within your route, only use "switchyard" consumer (i.e. "to") endpoints.  This keeps your routing logic independent of the binding details for consumed services.

Java DSL Routes

A newly created Java DSL route looks like this:

package com.example.switchyard.docs;

import org.apache.camel.builder.RouteBuilder;

public class CamelServiceRoute extends RouteBuilder {
    /**
     * The Camel route is configured via this method.  The from:
     * endpoint is required to be a SwitchYard service.
     */
    public void configure() {
        // TODO Auto-generated method stub
        from("switchyard://Example").log(
                "Received message for 'Example' : ${body}");
    }
}

There are no SwitchYard-specific classes or APIs used for Java DSL routes; the route class is identical in signature to what you would use with Apache Camel directly.  Since there is one route per service, you will have one RouteBuilder class for each Camel routing service in your application.  To add logic to your routing service, simply add additional logic to the configure() method.  For background and details on what you can do with the Java DSL, please consult the Apache Camel documentation.

XML Routes

A newly created XML route looks like this:

<?xml version="1.0" encoding="ASCII"?>
<route xmlns="http://camel.apache.org/schema/spring">
   <from uri="switchyard://Example"/>
   <log message="Example - message received: ${body}"/>
</route>

Like Java DSL routes, the XML routing syntax is identical to what you would use with Apache Camel directly and conforms to the Camel schema for <route> definitions.   There will be one file containing a route definition for each XML routing service in your application.

Consuming Services From Camel Routes

Invoking another service from within your Camel route can be done by using the SwitchYard producer endpoint (switchyard://) within your route.  Endpoint configuration is very straightforward:

switchyard://[service-name]?operationName=[operation-name]

• service-name : name of the SwitchYard service.  This value needs to match the name of a service reference defined on the service component for the route.

• operation-name : name of the service operation to be invoked.  This is only used on references and is optional if the target service only has a single operation.

A modified version of the default XML route which invokes a SwitchYard service can be found below:

<?xml version="1.0" encoding="ASCII"?>
<route xmlns="http://camel.apache.org/schema/spring">
   <from uri="switchyard://Example"/>
   <log message="Example - message received: ${body}"/>
   <!-- Invoke hasItem operation on WarehouseService -->
   <to uri="switchyard://WarehouseService?operationName=hasItem"/>
</route>

Scripting languages

Camel supports dynamic languages inside route logic in both XML and Java form. As the support for dynamic languages is built in JDK any language which provides javax.script.ScriptEngineManager may be used. However, because of 3rd party dependencies by default SwitchYard supports only following languages:

• BeanShell

• JavaScript

• Groovy

• Ruby

• Python

To use these script languages you have couple of options. They are available in expression-aware places like filter:

public class ScriptingBuilder extends RouteBuilder {

    public void configure() {
        from("switchyard://Inbound")
            .filter().javaScript("request.getHeader('myHeader') != null")
                .to("switchyard://Outbound");
    }
}

If you would like use dynamic language to implement your service you may use transform element:

public class ScriptingImplementationBuilder extends RouteBuilder {

    public void configure() {
        from("switchyard://Inbound")
            .transform().groovy("classpath:script.groovy"); // classpath resource

        from("switchyard://InboundBsh")
            .transform().language("beanshell", "file:script.bsh"); // file system resource
    }
}

Inside your script you will have access to predefined variables like request, response or exchange which will let you generate response.

CDI Integration

SwitchYard integrates the CDI Bean Manager with the Camel Bean Registry to allow you to reference CDI Beans in your Camel routes. Any Java class annotated with @Named in your application will be available through Camel's Bean registry.

Consider an example of where you have the following CDI bean:

@Named("StringSupport")
@ApplicationScoped
public class StringUtil {

    public String trim(String string) {
        return string.trim();
    }
}

This bean can be used inside your SwitchYard Camel Routes as follows:

public class ExampleBuilder extends RouteBuilder {

    public void configure() {
        from("switchyard://ExampleBuilder")
            .split(body(String.class).tokenize("\n"))
            .filter(body(String.class).startsWith("sally:"))
            .to("bean:StringSupport");
    }
}

See Camel's Bean Binding documentation for more details.

<route xmlns="http://camel.apache.org/schema/spring" id="CamelTestRoute">
   <log message="ItemId [${body}]"/>
   <to uri="switchyard://WarehouseService?operationName=hasItem"/>
   <log message="Title Name [${body}]"/>
   <log message="Properties [{{user.name}}]"/>
</route>

Overview

The BPM Component is a pluggable container in SwitchYard which allows a business process to be exposed as a service. One fronts their business process with a custom interface and, if desired, can easily annotate it's methods to define which should start a process, signal a process event, or abort a process.

Creating a BPM Service

To create a new BPM service in SwitchYard, you'll need the following information:

• File Name : the file name that will be used to create a new, empty BPMN 2 Process definition.

• Interface Type : the contract for the service being provided.  BPM supports Java, WSDL, and ESB contract types.

• Service Name : the name of the service your process will provide.

After clicking Finish, you will have a new service component definition for your process service and an empty BPMN process definition.  The next phase in developing your BPM service is to author the BPMN 2 process definition (details outside the scope of this documentation) and then configure the BPM service component to interact with that process definition.

Process Interaction

Interaction with a process is defined via actions on a BPM service component.  Take the following service contract as an example:

package org.switchyard.userguide;
public interface MyService {
    public void start(String data);
    public void signal(String data);
    public void stop(String data);
}

Actions allow you to map an operation in the service contract to one of the following interactions with a business process:

• START_PROCESS

• SIGNAL_EVENT

• ABORT_PROCESS_INSTANCE

<soap:Header>
    <bpm:processInstanceId xmlns:bpm="urn:switchyard-component-bpm:bpm:1.0">1</bpm:processInstanceId>
</soap:Header>

Process Variables

Consuming a Service

There are two ways of consuming Services with the SwitchYard BPM component:

1. Invoking the BPM implementation through a gateway binding.  Since the BPM component exposes a java interface fronting the business process, you can use any of the bindings provided by SwitchYard.  This could be a SOAP Binding or a Camel Binding, for example. (Please refer to those sections of this guide for more information.)

2. Invoking other SwitchYard Services from inside a BPM process itself.  To do this, you can use the SwitchYardServiceWorkItemHandler, which is provided out-of-the-box.  To make authoring BPMN2 processes easier, SwitchYard provides a new widget for the Eclipse BPMN2 Modeler visual editor palette. Here is a screenshot from the "Help Desk" demo quickstart:

On the bottom right hand side under "Custom Task", you can see the SwitchYard Service widget. On the left hand side, you can see the various points of the business process where SwitchYard Services are being invoked. Once you have dropped a SwitchYard Service task in the main window, you can customize it via the Eclipse Properties Editor.

You can read a more detailed explanation of the Help Desk quickstart demo, as well as how to set up Eclipse to make use of new widget, on this wiki page.

SwitchYard Service Fault Handling

During your process execution, the SwitchYardServiceWorkItemHandler class is used to handle Switchyard Service tasks.  It executes service references, per the properties specified in the panel above.  Pay particular attention to the list of Fault-Handling Properties.  These properties define the behavior of the SwitchYardServiceWorkItemHandler in the case were a fault is encountered when executing the service reference.  There are 2 scenarios that the fault-handling covers:

1. "In my process flow, after the SwitchYard Service task, I would like a split gateway where I can inspect a process variable (a "flag") that can tell me that a fault occurred, so that I can diverge one way or another." 

   • To do this, specify the FaultResultName property.  The SwitchYardServiceWorkItemHandler will make the fault itself available as an output parameter of the task, so that it can be associated with a process variable, and inspected for existence in your split gateway.  You must also set the FaultWorkItemAction property to complete, so that the process will continue on to your split gateway!

   • An example bpmn2 process can be found in our JUnit test suite here: BPMWorkTests-FaultResultProcess.bpmn

2. "In my process flow, I have multiple places where faults could occur, and I want to have one shared path of fault-handling." 

   • To do this, specify the FaultSignalId property.  This must match a signal id you specify in your bpmn2 process definition.  You can then add an event node in your process that is triggered with this signal id; the flow from that event node on is your fault-handling path. The SwitchYardServiceWorkItemHandler will then signal the proper event with the configured id.

   • An example bpmn2 process can be found in our JUnit test suite here: BPMWorkTests-FaultEventrocess.bpmn

Whether you choose scenario 1 or 2 above, the question remains "What next?"  If you don't specify a FaultWorkItemAction property, nothing is done.  The work item is not completed, nor is it aborted.  You can set the property to complete to complete the work item after a fault, or you can set the property to abort to abort the work item after a fault.

Resources

A Resource represents an artifact that is required by your BPM process. It could be anything you could think of, including a properties file, a Drools Rule Language file, or whatever.  But it needs to be available to the BPM component's runtime for that process.  The list of resources available to your process is a configurable aspect of the BPM service component.

WorkItemHandlers

A WorkItemHandler is a way for you to add your own code into the business process.  Simply implement the org.kie.runtime.process.WorkItemHandler interface and add a handler definition to your BPM service component.

By default, the SwitchYardServiceWorkItemHandler is always added for you by the SwitchYard Maven plugin.  That handler allows you to easily call out to other SwitchYard services by name within your business process. Please see the section "Consuming a BPM Service" below for more information.

Auditing a Process

Please see the Listeners and Loggers sections found in the Knowledge Services documentation.

Overview

The Rules Component is a pluggable container in SwitchYard which allows business rules to be exposed as a service.  One fronts their rules with a custom interface and, if desired, can easily annotate it's methods to define which should execute the rules. The Rules Component currently supports Drools as the rule engine.  Even though it is quite simple to write rules in Drools, that project's developer tooling and business analyst tooling are very mature.

Creating a Rules Service

To create a new Rules service in SwitchYard, you'll need the following information

• File Name : the file name that will be used to create a new template rules definition.

• Interface Type : the contract for the service being provided.  Rules services support Java, WSDL, and ESB contract types.

• Service Name : the name of the service your process will provide.

• Package Name : package name used for the new Rules file.

The MyService interface can be as simple as this, with no SwitchYard-specific imports:

package com.example.switchyard.docs;
public interface Example {
    public void process(MyData data);
}

The generated rule template will look like this:

package com.example.switchyard.docs
import org.switchyard.Message
global Message message

rule "RulesExample"
    when
        // insert conditional here
    then
        // insert consequence here
        System.out.println("service: ExampleService, payload: " + message.getContent());
end

package example

global java.lang.String service
global java.lang.String messageId
global com.example.Payload payload

rule "Example"
    when
        ...
    then
        ...
        System.out.println("service: " + service + ", messageId: " + messageId + ", payload: " + payload);
end

<implementation.rules ...>
    <actions>
        <action id="FooStream" operation="processFooMessage" type="FIRE_UNTIL_HALT"/>
        <action id="BarStream" operation="processBarMessage" type="FIRE_UNTIL_HALT"/>
    </actions>
    ...
    <properties>
        <property name="drools.clockType" value="realtime"/>
        <property name="drools.eventProcessingMode" value="stream"/>
        <property name="drools.maxThreads" value="1"/>
        <property name="drools.multithreadEvaluation" value="false"/>
    </properties>
</implementation.rules>

Providing a Service

To provide a service with the BPEL component, you will have to:

1. Define your process using WS-BPEL (e.g. using the Eclipse BPEL editor bundled with JBossTools).

2. Define a WSDL interface for the BPEL service.

3. Define a Deployment Descriptor (e.g. using the ODE Deployment Descriptor editor bundled with JBossTools).

4. Add the component containing the implementation and service interface to the SwitchYard configuration.

Here is an example of the component section of the SwitchYard configuration:

<sca:component name="SayHelloService">
    <bpel:implementation.bpel process="sh:SayHello" />
    <sca:service name="SayHelloService">
        <sca:interface.wsdl interface="SayHelloArtifacts.wsdl#wsdl.porttype(SayHello)"/>
    </sca:service>
</sca:component>

The BPEL component contains a single 'implementation.bpel' element that identifies the fully qualified name of the BPEL process.

The component may also contain one or more service elements defining the WSDL port types through which the BPEL process can be accessed.

In the packaged Switchyard application, the BPEL process associated with this fully qualified name, must be present within the root folder of the distribution, along with the deployment descriptor (deploy.xml). An example of the deployment descriptor for the BPEL process referenced above is:

<deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03"
	xmlns:examples="http://www.jboss.org/bpel/examples" >

	<process name="examples:SayHello">
		<active>true</active>
		<retired>false</retired>
		<process-events generate="all"/>
		<provide partnerLink="client">
			<service name="examples:SayHelloService" port="SayHelloPort"/>
		</provide>
	</process>
</deploy>

Consuming a Service

This section describes how a BPEL process can invoke other services.

The first step is to define the WSDL interface(s), representing the service(s) to be consumed, using an invoke element within the deployment descriptor, e.g.

<process name="ls:loanApprovalProcess">
		<active>true</active>
		<process-events generate="all"/>
		<provide partnerLink="customer">
			<service name="ls:loanService" port="loanService_Port"/>
		</provide>
		<invoke partnerLink="assessor" usePeer2Peer="false">
			<service name="ra:riskAssessor" port="riskAssessor_Port"/>
		</invoke>
	</process>

The 'usePeer2Peer' property informs the BPEL engine not to use internal communications for sending messages between BPEL processes that may be executing within the same engine, and instead pass messages through the SwitchYard infrastructure.

For each consumed service, we then need to create a reference element within the SwitchYard configuration, to locate the WSDL file and identify the port type associated with the required WSDL service/port.

<sca:component name="loanService">
             <bpel:implementation.bpel process="ls:loanApprovalProcess" />
             <sca:service name="loanService">
                 <sca:interface.wsdl interface="loanServicePT.wsdl#wsdl.porttype(loanServicePT)"/>
             </sca:service>
             <sca:reference name="riskAssessor" >
                 <sca:interface.wsdl interface="riskAssessmentPT.wsdl#wsdl.porttype(riskAssessmentPT)"/>
             </sca:reference>
         </sca:component>

.....
<bpel:copy>
     <bpel:from xmlns:property="java:org.switchyard.component.bpel.riftsaw.SwitchYardPropertyFunction"
                expressionLanguage="urn:oasis:names:tc:wsbpel:2.0:sublang:xpath2.0">
         <![CDATA[concat(property:resolveProperty('Greeting'), $ReceiveSayHelloVar.parameters/tns:input)]]>
     </bpel:from>
     <bpel:to part="parameters" variable="ReplySayHelloVar">
         <bpel:query queryLanguage="urn:oasis:names:tc:wsbpel:2.0:sublang:xpath1.0"><![CDATA[tns:result]]></bpel:query>
     </bpel:to>
</bpel:copy>

Maintain Multiple Versions of a BPEL Process

BPEL processes can be used to implement long lived stateful business processes. However the BPEL process may need to change, over the course of its lifetime, to accomodate new requirements.

This introduces the problem of how to deal with existing active instances of the BPEL process that may not complete for weeks, months or even years. In these situations we need to have a strategy for dealing with multiple version of a BPEL process, to enable new requirements to be introduced, while still preserving the original process definitions associated with existing active process instances.

This is achieved by simply associating a version number with the BPEL process by adding it as a suffix to the BPEL file name. For example, if our BPEL process would normally be located in the file 'HelloWorld.bpel', then we simply add a hyphen followed by the version number, e.g. 'HelloWorld-32.bpel' would indicate that this is the 32nd version of this BPEL process.

When a new version of the BPEL process has been defined, it is packaged in the SwitchYard application, along side the previous versions of the BPEL process. It is important that the older version of the BPEL process remain in the SwitchYard application until there are no longer any active process instances associated with that version.

It is then important that the SwitchYard application is re-deployed, without undeploying the previous version. If the previous version of the SwitchYard application is undeployed, it will cause the BPEL engine to delete all outstanding active instances associated with the process definitions that have bene removed.

Although the BPEL process is versioned, the WSDL interfaces are not. It is important to ensure that any changes made to the WSDL interfaces are backward compatible, so that both the new and older versions of the BPEL (that still have active process instances) are not affected by the changes.

Structure of a SwitchYard BPEL Application

The following image shows the structure of the say_hello SwitchYard BPEL quickstart:

The important part is how the artifacts are structured within the src/main/resources folder.

The switchyard.xml configuration file is located in the META-INF folder as usual. However the BPEL deployment descriptor (deploy.xml), and the BPEL process definition are located in the root folder.

The WSDL interface definitions, and any accompanying XSD schemas, can be located in sub-folders. If they are, then the BPEL process and SwitchYard BPEL component configuration must define the correct relative path.

SOAP

The SOAP component in SwitchYard provides SOAP-based web service binding support for services and references in SwitchYard. 

<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
    <sca:service name="OrderService" promote="OrderService">
        <soap:binding.soap>
            <soap:wsdl>wsdl/OrderService.wsdl</soap:wsdl>
            <soap:socketAddr>:9000</soap:socketAddr>        
         </soap:binding.soap>
    </sca:service>
</sca:composite>

<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
    <sca:reference name="WarehouseService" promote="OrderComponent/WarehouseService" multiplicity="1..1">
         <soap:binding.soap>
            <soap:wsdl>wsdl/OrderService.wsdl</soap:wsdl>
            <soap:endpointAddress>http://www.change.com/toanewendpointurl</soap:endpointAddress>
         </soap:binding.soap>
    </sca:reference>
</sca:composite>

  <binding name="WorkServiceBinding" type="tns:WorkService">
    <wsp:PolicyReference URI="#WorkServicePolicy"/>
    ...
  </binding>
  <wsp:Policy wsu:Id="WorkServicePolicy">
    <wsp:ExactlyOne>
      <wsp:All>
        <sp:SupportingTokens xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
          <wsp:Policy>
            <sp:UsernameToken sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
              <wsp:Policy>
                <sp:WssUsernameToken10/>
              </wsp:Policy>
            </sp:UsernameToken>
          </wsp:Policy>
        </sp:SupportingTokens>
      </wsp:All>
    </wsp:ExactlyOne>
  </wsp:Policy>

  <binding.soap xmlns="urn:switchyard-component-soap:config:1.0">
    <wsdl>META-INF/WorkService.wsdl</wsdl>
    <contextPath>policy-security-wss-username</contextPath>
    <securityAction>UsernameToken</securityAction>
  </binding.soap>

<jboss-web>
    <security-domain>java:/jaas/other</security-domain>
</jboss-web>

  <binding.soap xmlns="urn:switchyard-component-soap:config:1.0">
    <wsdl>META-INF/WorkService.wsdl</wsdl>
    <contextPath>policy-security-wss-username</contextPath>
    <inInterceptors>
      <interceptor class="com.example.MyInterceptor"/>
    </inInterceptors>
  </binding.soap>

public class MyInterceptor extends WSS4JInterceptor {
  private static final PROPS;
  static {
    Map<String,String> props = new HashMap<String,String>();
    props.put("action", "Signature Encryption");
    props.put("signaturePropFile", "META-INF/bob.properties");
    props.put("decryptionPropFile", "META-INF/bob.properties");
    props.put("passwordCallbackClass", "com.example.MyCallbackHandler");
    PROPS = props;
  }
  public MyInterceptor() {
    super(PROPS);
  }
}

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=password
org.apache.ws.security.crypto.merlin.keystore.alias=bob
org.apache.ws.security.crypto.merlin.file=META-INF/bob.jks

HTTP

The HTTP component in SwitchYard provides HTTP-based binding support for services and references in SwitchYard. 

Composite-level services can be exposed as a HTTP-based service using the <binding.http> binding definition.  The following configuration options are available for binding.rest when binding services:

• operationSelector : specification of the operation to use for the message exchange. See Operation Selector for more details.

• contextPath : A context path for the HTTP endpoint.

Here's an example of what a HTTP service binding looks like:

<sca:service name="QuoteService" promote="StockService/QuoteService">
    <http:binding.http>
        <selector:operationSelector operationName="getPrice"/>
        <http:contextPath>http-binding/quote</http:contextPath>
    </http:binding.http>
</sca:service>

Binding a reference with HTTP can be used to make HTTP-based services available to SwitchYard services. The following configuration options are available for binding.http when binding references:

• address : A URL that points to the HTTP endpoint. It is optional and if not specified will default to http://127.0.0.1:8080/.

• method : The HTTP method used for invoking the endpoint. Default is GET.

• contentType : The HTTP Content-Type header that needs to be set on the request.

Here's an example of what a REST reference binding looks like:

<sca:reference name="Symbol" promote="StockService/SymbolService" multiplicity="1..1">
    <http:binding.http>
        <http:address>http://localhost:8080/http-binding/symbol</http:address>
        <http:method>POST</http:method>
        <http:contentType>text/plain</http:contentType>
    </http:binding.http>
</sca:reference>

RESTEasy

The RESTEasy component in SwitchYard provides REST-based binding support for services and references in SwitchYard. 

Composite-level services can be exposed as a REST-based service using the <binding.rest> binding definition.  The following configuration options are available for binding.rest when binding services:

• interfaces : A comma seperated list of interfaces or abstract/empty classes with JAX-RS annotations.

• contextPath : Additional context path for the REST endpoint. Default is none.

Here's an example of what a REST service binding looks like:

<sca:service name="OrderService" promote="OrderService/OrderService">
    <rest:binding.rest>
        <rest:interfaces>org.switchyard.quickstarts.rest.binding.OrderResource,org.switchyard.quickstarts.rest.binding.TestResource</rest:interfaces>
        <rest:contextPath>rest-binding</rest:contextPath>
    </rest:binding.rest>
</sca:service>

Binding a reference with REST can be used to make REST-based services available to SwitchYard services. The following configuration options are available for binding.rest when binding references:

• interfaces : A comma seperated list of interfaces or abstract/empty classes with JAX-RS annotations.

• address : A URL that points to the root path of resources. This is only applicable for Reference bindings. It is optional and if not specified will default to http://127.0.0.1:8080/.

• contextPath : Additional context path for the REST endpoint. Default is none.

Here's an example of what a REST reference binding looks like:

<sca:reference name="Warehouse" promote="OrderService/Warehouse" multiplicity="1..1">
    <rest:binding.rest>
        <rest:interfaces>org.switchyard.quickstarts.rest.binding.WarehouseResource</rest:interfaces> 
        <rest:address>http://localhost:8080</rest:address>
        <rest:contextPath>rest-binding</rest:contextPath>
    </rest:binding.rest>
</sca:reference>

In this example above the resource URLs will start from http://localhost:8080/rest-binding.

JCA

The JCA gateway allows you to send and receive messages to/from EIS via JCA ResourceAdapter.

Composite-level services can be bound to a EIS with JCA message inflow using the <binding.jca> binding definition.  The following configuration options are required for binding.jca:

• operationSelector : specification of the operation to use for the message exchange. See Operation Selector for more details.

• inboundConnection

  • resourceAdapter

    • @name : Name of the ResourceAdapter archive. Please make sure the resource adapter has been deployed on JBoss application server before you deploy the SwitchYard application which has JCA binding.

  • activationSpec

    • property : Properties to be injected into ActivationSpec instance. Required properties are specific to the ResourceAdapter implementation.

• inboundInteraction

  • listener : FQN of the listener interface. When you use JMSEndpoint, javax.jms.MessageListener should be specified. When you use CCIEndpoint, javax.resource.cci.MessageListener should be specified. Otherwise, you may need to specify EIS specific listener interface according to its ResourceAdapter. Note that the endpoint class should implement this listener interface.

  • endpoint

    • @type : FQN of the Endpoint implementation class. There are 2 built-in Endpoint, org.switchyard.component.jca.endpoint.JMSEndpoint and org.switchyard.component.jca.endpoint.CCIEndpoint. Note that these 2 have corresponding listener. If neither JMSEndpoint nor CCIEndpoint is applicable for the EIS you're supposed to bind to, then you need to implement its own Endpoint class according to the ResourceAdapter implementation. The Endpoint class should be a subclass of org.switchyard.component.jca.endpoint.AbstractInflowEndpoint.

    • property : Properties to be injected into Endpoint class. JMSEndpoint has no required property. CCIEndpoint needs connectionFactoryJNDIName property.

  • transacted : The boolean value to indicate whether transaction is needed by endpoint or not. True by default.

  • batchCommit : Multiple incoming messages are processed in one transaction if you define this element. The transaction is committed when the number of processed messages reach to batchSize, or batchTimeout milliseconds pass since the transaction is started. Transaction reaper thread is watching inflight transaction, and once batch timeout occurs the transaction reaper thread commits it.

    • @batchSize : The number of messages to be processed in one transaction

    • @batchTimeout : The batch timeout in milliseconds

Here's an example of what a JCA service binding looks like. This example binds a service to the HornetQ JMS:

<sca:composite name="JCAInflowExample" targetNamespace="urn:userguide:jca-example-service:0.1.0">
    <sca:service name="JCAService" promote="SomeService">
        <jca:binding.jca>
            <selector:operationSelector operationName="onMessage"/>
            <jca:inboundConnection>
                <jca:resourceAdapter name="hornetq-ra.rar"/>
                <jca:activationSpec>
                    <jca:property name="destinationType" value="javax.jms.Queue"/>
                    <jca:property name="destination" value="ServiceQueue"/>
                </jca:activationSpec>
            </jca:inboundConnection>
            <jca:inboundInteraction>
                <jca:listener>javax.jms.MessageListener</jca:listener>
                <jca:endpoint type="org.switchyard.component.jca.endpoint.JMSEndpoint"/>
                <jca:transacted>true</jca:transacted>
                <jca:batchCommit batchSize="10" batchTimeout="5000"/>
            </jca:inboundInteraction>
        </jca:binding.jca>
    </service>
    <!-- sca:component definition omitted -->
</sca:composite>

Composite-level references can be bound to a EIS with JCA outbound using the <binding.jca> binding definition.  The following configuration options are required for binding.jca:

• outboundConnection

  • resourceAdapter

    • @name : Name of the ResourceAdapter archive. Please make sure the resource adapter has been deployed on JBoss application server before you deploy the SwitchYard application which has JCA binding.

  • connection

    • @jndiName : JNDI name which the ConnectionFactory is bound into.

• outboundInteraction

  • connectionSpec : Configuration for javax.resource.cci.ConnectionSpec. Note that JMSProcessor doesn't use this option.

    • @type : FQN of the ConnectionSpec implementation class.

    • property : Properties to be injected into ConnectionSpec instance. 

  • interactionSpec : Configuration for _javax.resource.cci.InteractionSpec. _Note that JMSProcessor doesn't use this option.

    • @type : FQN of the InteractionSpec implementation class.

    • property : Properties to be injected into InteractionSpec instance.

  • processor

    • @type : FQN of the class which processes outbound delivery. There are 2 build-in processor, org.switchyard.component.jca.processor.JMSProcessor and org.switchyard.component.jca.processor.CCIProcessor. If neither JMSProcessor nor CCIProcessor is applicable for the EIS you're supposed to bind to, then you need to implement its own processor class according to the ResourceAdapter implementation. Note that this class should be a subclass of org.switchyard.component.jca.processor.AbstractOutboundProcessor.

    • property : Properties to be injected into processor instance. JMSProcessor needs destination property to specify target destination. CCIProcessor needs recordClassName property to specify record type to be used to interact with EIS. If you use CCIProcessor with the record type other than MappedRecord and IndexedRecord, you need to implement corresponding RecordHandler. Please refer to org.switchyard.component.jca.processor.cci.IndexedRecordHandler and org.switchyard.component.jca.processor.cci.MappedRecordHandler.

Here's an example of what a JCA reference binding looks like. This example binds a reference to the HornetQ JMS:

<sca:composite name="JCAReferenceExample" targetNamespace="urn:userguide:jca-example-reference:0.1.0">
    <sca:reference name="JCAReference" promote="SomeComponent/SomeReference" multiplicity="1..1">
        <jca:binding.jca>
            <jca:outboundConnection>
                <jca:resourceAdapter name="hornetq-ra.rar"/>
                <jca:connection jndiName="java:/JmsXA"/>
            </jca:outboundConnection>
            <jca:outboundInteraction>
                <jca:processor type="org.switchyard.component.jca.processor.JMSProcessor">
                    <jca:property name="destination" value="ReferenceQueue"/>
                </jca:processor>
            </jca:outboundInteraction>
        </jca:binding.jca>
    </sca:reference>
</sca:composite>

JMS

The JMS binding in SwitchYard provides support for asynchronous communication with messaging providers. It supports both sides - service and reference.  The JMS binding is built on top of camel-jms and supports most of options for this endpoint. Please reffer camel documentation for detailed description of them.

Here's an example of what a jms service binding looks like:

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.jms>
            <camel:queue>INCOMING_GREETS</camel:queue>
            <camel:connectionFactory>#connectionFactory</camel:connectionFactory>
            <camel:username>esb</camel:username>
            <camel:password>rox</camel:password>
            <camel:selector>RECEIVER='ESB' AND SENDER='ERP'<camel:selector>
        </camel:binding.jms>
    </sca:service>
</sca:composite>

File

The file binding in SwitchYard provides filesystem level support for services and references in SwitchYard.

The file binding is built on top of camel-file and supports most of options for this endpoint. Please refer camel documentation for detailed description of them.

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.file>
            <camel:directory>target/input</camel:directory>
            <camel:fileName>test.txt</camel:fileName>
            <camel:consume>
               <camel:initialDelay>50</camel:initialDelay>
               <camel:delete>true</camel:delete>
            </camel:consume>
        </camel:binding.file>
    </sca:service>
</sca:composite>

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:reference name="GreetingService" promote="camel-binding/GreetingService" multiplicity="1..1">
        <camel:binding.file>
            <camel:directory>target/output</camel:directory>
            <camel:autoCreate>false</camel:autoCreate>
            <camel:produce>
                <camel:fileExist>Override</camel:fileExist>
            </camel:produce>
        <camel:binding.file>
    </sca:reference>
</sca:composite>

FTP FTPS SFTP

SwitchYard provides support for remote file systems on both sides service and reference.

The ftp binding is built on top of camel-ftp and supports most of options for this endpoint. Please refer camel documentation for detailed description of them.

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.ftp>
            <camel:directory>target/input</camel:directory>
            <camel:host>localhost</camel:host>
            <camel:port>22</camel:port>
            <camel:username>camel</camel:username>
            <camel:password>secret</camel:password>
            <camel:consume>
               <camel:initialDelay>50</camel:initialDelay>
               <camel:delete>true</camel:delete>
            </camel:consume>
        </camel:binding.file>
    </sca:service>
</sca:composite>

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:reference name="GreetingService" promote="camel-binding/GreetingService" multiplicity="1..1">
        <camel:binding.ftp>
            <camel:directory>target/output</camel:directory>
            <camel:autoCreate>false</camel:autoCreate>
            <camel:host>localhost</camel:host>
            <camel:port>22</camel:port>
            <camel:username>camel</camel:username>
            <camel:password>secret</camel:password>
            <camel:produce>
                <camel:fileExist>Override</camel:fileExist>
            </camel:produce>
        <camel:binding.ftp>
    </sca:reference>
</sca:composite>

TCP UDP

SwitchYard provides support for network level integration with TCP and UPD protocols.

The TCP and UDP binding is built on top of camel-netty and supports most of options for this endpoint. Please refer camel documentation for detailed description of them.

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.tcp>
            <camel:host>localhost</camel:host>
            <camel:port>3939</camel:port>
            <camel:allowDefaultCodec>false</camel:allowDefaultCodec>
            <camel:sync>false</camel:sync>
        </camel:binding.tcp>
        <camel:binding.udp>
            <camel:host>localhost</camel:host>
            <camel:port>3940</camel:port>
            <camel:allowDefaultCodec>false</camel:allowDefaultCodec>
            <camel:sync>false</camel:sync>
        </camel:binding.udp>
    </sca:service>
</sca:composite>

JPA

The jpa binding in SwitchYard provides support for consuming and storing JPA entities. It supports both sides - service binding for entity consumption and reference for entity storing.

The JPA binding is built on top of camel-jpa and supports most of options for this endpoint. Please reffer camel documentation for detailed description of them.

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.jpa>
            <camel:entityClassName>org.switchyard.quickstarts.camel.jpa.binding.domain.Greet</camel:entityClassName>
            <camel:persistenceUnit>JpaEvents</camel:persistenceUnit>
            <camel:transactionManager>#jtaTransactionManager</camel:transactionManager>
            <camel:consume>
                <camel:consumeLockEntity>false</camel:consumeLockEntity>
                <camel:consumer.transacted>true</camel:consumer.transacted>
            </camel:consume>
        </camel:binding.jpa>
    </sca:service>
</sca:composite>

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:reference name="GreetingService" promote="camel-binding/GreetingService" multiplicity="1..1">
        <camel:binding.jpa>
            <camel:entityClassName>org.switchyard.quickstarts.camel.jpa.binding.domain.Greet</camel:entityClassName>
            <camel:persistenceUnit>JpaEvents</camel:persistenceUnit>
            <camel:produce>
                <camel:flushOnSend>false</camel:flushOnSend>
            </camel:produce>
        </camel:binding.jpa>
    </sca:reference>
</sca:composite>

SQL

The sql binding in SwitchYard provides database read/write support for references in SwitchYard.

The file binding is built on top of camel-sql.

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.sql period="10s">
            <camel:query>SELECT * FROM greetings</camel:query>
            <camel:dataSourceRef>java:jboss/datasources/GreetDS</camel:dataSourceRef>
        </camel:binding.sql>
    </sca:service>
</sca:composite>

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:reference name="GreetingDatabaseStore" promote="camel-binding/GreetingDatabaseStore" multiplicity="1..1">
        <camel:binding.sql>
            <camel:query>INSERT INTO greetings (name) VALUES (#)</camel:query>
            <camel:dataSourceRef>java:jboss/datasources/GreetDS</camel:dataSourceRef>
        <camel:binding.sql>
    </sca:reference>
</sca:composite>

Mail

The mail binding in SwitchYard provides support for consuming and sending mail messages. It supports both sides - service binding for mail consumption and reference for message sending.

The Mail binding is built on top of camel-mail and supports most of options for this endpoint. Please reffer camel documentation for detailed description of them.

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.mail>
            <camel:host>localhost</camel:host>
            <camel:username>camel</camel:username>
            <camel:consume accountType="pop3">
                <camel:copyTo>after-processing</camel:copyTo>
            </camel:consume>
        </camel:binding.mail>
    </sca:service>
</sca:composite>

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:reference name="GreetingService" promote="camel-binding/GreetingService" multiplicity="1..1">
        <camel:binding.mail>
            <camel:host>localhost</camel:host>
            <camel:username>camel</camel:username>
            <camel:produce>
                <camel:subject>Forwarded message</camel:subject>
                <camel:from>camel@localhost</camel:from>
                <camel:to>rider@camel</camel:to>
            </camel:produce>
        </camel:binding.mail>
    </sca:reference>
</sca:composite>

Quartz

The quartz binding in SwitchYard provides support for triggering services with given cron expression.

The quartz binding is built on top of camel-quartz.

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.quartz>
            <camel:name>GreetingJob</camel:name>
            <camel:cron>0 0/5 * * * ?</camel:cron>
        </camel:binding.quartz>
    </sca:service>
</sca:composite>

Timer

The timer binding in SwitchYard provides support for triggering services with fixed timer. It's lightweight alternative for Quartz.

The file binding is built on top of camel-timer. Please refer camel documentation for detailed description of options.

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.timer>
            <camel:name>GreetingTimer</camel:name>
            <camel:time>2012-01-01T12:00:00</camel:time>
            <camel:pattern>yyyy-MM-dd'T'HH:mm:ss</camel:pattern>
            <camel:delay>1000</camel:delay>
            <camel:fixedRate>true</camel:fixedRate>
        </camel:binding.timer>
    </sca:service>
</sca:composite>

SEDA

The SEDA binding in SwitchYard provides asynchronous service binding between camel route and SwitchYard service.

This binding is built on top of camel-seda. Please refer camel documentation for detailed description of options.

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.seda>
            <camel:name>GreetingQueue</camel:name>
            <camel:size>6</camel:size>
            <camel:concurrentConsumers>2</camel:concurrentConsumers>
        </camel:binding.seda>
    </sca:service>
</sca:composite>

Camel URI

Camel binding support in SwitchYard allows Camel components to be used as gateway bindings for services and references within an application.

<sca:composite name="SimpleCamelService" targetNamespace="urn:userguide:simple-camel-service:0.1.0">
    <sca:service name="SimpleCamelService" promote="SimpleComponent/SimpleCamelService">
        <camel:binding.uri configURI="file://target/input?fileName=test.txt&amp;initialDelay=50&amp;delete=true">
            <selector:operationSelector operationName="print"/>
        </camel:binding.uri>
    </sca:service>
    <!-- sca:component definition omitted -->
</sca:composite>

<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
    <sca:reference name="WarehouseService" promote="OrderComponent/WarehouseService" multiplicity="1..1">
        <camel:binding.uri configURI="file://target/output"/>
    </sca:reference>
</sca:composite>

Custom Message Composers

To implement a custom MessageComposer, you need to implement the org.switchyard.component.common.composer.MessageComposer interface:

public interface MessageComposer<T> {
    ContextMapper<T> getContextMapper();
    MessageComposer<T> setContextMapper(ContextMapper<T> contextMapper);
    Message compose(T source, Exchange exchange, boolean create) throws Exception;
    public T decompose(Exchange exchange, T target) throws Exception;
}

• The getContextMapper() and setContextMapper() methods are just bean properties. If you extend BaseMessageComposer, both of these are implemented for you.

• Your compose() method needs to take the data from the passed in source native message and compose a SwitchYard Message based on the specified Exchange.  The create parameter is whether or not we ask the Exchange to create a new Message, or just get the existing one.

• Your decompose() method needs to take the data from the SwitchYard Message in the specified Exchange and decompose it into the target native message.

Then, specify your implementation in your switchyard.xml:

<binding.xyz ...>
    <messageComposer class="com.example.MyMessageComposer"/>
</binding.xyz>

Custom Context Mappers

To implement a custom ContextMapper, you need to implement the org.switchyard.component.common.composer.ContextMapper interface:

public interface ContextMapper<T> {
    void mapFrom(T source, Context context) throws Exception;
    void mapTo(Context context, T target) throws Exception;
}

• Your mapFrom() method needs to map a source native message's properties to the SwitchYard Message's Context.

• Your mapTo() method needs to map a SwitchYard Message's Context properties into the target native message.

• If you extend BaseContextMapper, these methods are stubbed-out with no-op implementations so you only have to implement what you want to.

Then, specify your implementation in your switchyard.xml:

<binding.xyz ...>
    <contextMapper class="com.example.MyContextMapper"/>
</binding.xyz>

Alternatively, you can implement the org.switchyard.component.common.composer.RegexContextMapper.  The purpose of this interface is to add regular expression support, where you can filter exactly which Context properties get mapped:

public interface RegexContextMapper<T> extends ContextMapper<T> {
    ContextMapper<T> setIncludes(String includes);
    ContextMapper<T> setExcludes(String excludes);
    ContextMapper<T> setIncludeNamespaces(String includeNamespaces);
    ContextMapper<T> setExcludeNamespaces(String excludeNamespaces);
    boolean matches(String name);
    boolean matches(QName qname);
}

• The setIncludes(), setExcludes(), setIncludeNamespaces() and setExcludeNamespaces() methods are just bean properties. The matches() methods use those bean properties to determine if the specified name or qualified name passes the collective regular expressions.

• If you extend BaseRegexContextMapper, all of these are implemented for you.  Then, in your implementation's mapFrom / mapTo methods, you only need to first check if the property matches before you map it.

If your implementation extends RegexContextMapper, the following additional (regular expression valued) attributes of the <contextMapper/> element become meaningful/respected:

• includes = Which context property names to include.

• excludes = Which context property names to exclude.

• includeNamespaces = Which context property namespaces to include (if the property name is a qualified name).

• excludeNamespaces = Which context property namespaces to exclude (if the property name is a qualified name).

OOTB Implementation Notes

Note: All of the out-of-the-box implementations below extend BaseRegexContextMapper, thus all can be configured with the regular expression attributes described above.

• The SOAPContextMapper, when processing an incoming SOAPMessage, takes the mime (in most cases, HTTP) headers from a soap envelope and maps them into the SwitchYard Context as Scope.IN properties with the SOAPComposition.SOAP_MESSAGE_MIME_HEADER label, and takes the soap header elements from the soap envelope and maps them into the SwitchYard Context as Scope.EXCHANGE properties with the SOAPComposition.SOAP_MESSAGE_HEADER label. When processing an outgoing SOAPMessage, it takes the SwitchYard Scope.OUT Context properties and maps them into mime (in most cases, HTTP) headers, and takes the SwitchYard Scope.EXCHANGE Context properties and maps them into the soap envelope as soap header elements.

<binding.soap>
    <contextMapper includes=".*" soapHeadersType="VALUE"/>
</binding.soap>

• The CamelContextMapper, when processing an incoming CamelMessage, takes the CamelMessage headers and maps them into the SwitchYard Context as Scope.IN properties with the CamelComposition.CAMEL_MESSAGE_HEADER label, and takes the Camel Exchange properties and maps them into the SwitchYardContext as Scope.EXCHANGE properties with the CamelComposition.CAMEL_EXCHANGE_PROPERTY label.  When processing an outgoing CamelMessage, it takes the SwitchYard Scope.OUT Context properties and maps them into the CamelMessage as headers, and takes the SwitchYard Scope.EXCHANGE Context properties and maps them into the Camel Exchange as properties.

• The HornetQContextMapper, when processing an incoming ClientMessage, takes the ClientMessage properties and maps them into the SwitchYardContext as Scope.EXCHANGE properties with the HornetQCompsition.HORNETQ_MESSAGE_PROPERTY label.  When procesing an outgoing ClientMessage, it takes the SwitchYard Scope.EXCHANGE Context properties and maps them into the ClientMessage as properties.  There is no concept of "headers" in a HornetQ ClientMessage.

• The HTTPContextMapper, when processing an incoming HTTP request, takes the incoming request headers and maps them into the SwitchYard Context as Scope.IN with the HttpComposition.HTTTP_HEADER label.  When processing an outgoing HTTP response, it takes the SwitchYard Scope.OUT Context properties and maps them into the response headers.

• The RESTEasyContextMapper, when processing an incoming HTTP request, takes the incoming request headers and maps them into the SwitchYard Context as Scope.IN with the RESTEasyComposition.HTTP_HEADER label.  When processing an outgoing HTTP response, it takes the SwitchYard Scope.OUT Context properties and maps them into the response headers.

• The JCA Component actually has 3 different ContextMappers:

  • The CCIIndexedRecordContextMapper, when processing an incoming IndexedRecord, takes the record name and record short description and maps them into the SwitchYardContext as Scope.EXCHANGE properties with the JCAComposition.JCA_MESSAGE_PROPERTY label.  When processing an outgoing IndexedRecord, it looks for those properties specifically in the SwitchYard.EXCHANGE Context properties by key and sets them on the IndexedRecord.

  • The CCIMappedRecordContextMapper, when processing an incoming MappedRecord, takes the record name and record short description and maps them into the SwitchYardContext as Scope.EXCHANGE properties with the JCAComposition.JCA_MESSAGE_PROPERTY label.  When processing an outgoing MappedRecord, it looks for those properties specifically in the SwitchYard.EXCHANGE Context properties by key and sets them on the MappedRecord.

  • The JMSContextMapper, when processing an incoming (JMS) Message, takes the Message properties and maps them into the SwitchYardContext as Scope.EXCHANGE properties with the JCAComposition.JCA_MESSAGE_PROPERTY label. When processing an outgoing (JMS) Message, it takes the SwitchYard.EXCHANGE Context properties and maps them into the Message as Object properties.

The reasoning of scoping headers as IN and OUT scopes was modeled after the notion of http headers, where you will see some headers specifically useful for http requests, and other headers specifically useful for http responses.  In both cases, they are most likely tied to the binding's notion of an incoming message or an outgoing message.

The reasoning of scoping properties as EXCHANGE scope came from the idea that this is most likely application or domain data, and possibly useful in the entire processing of the Exchange.  An example of this would be a processInstanceId when using the BPM Component.

Static Operation Selector

specify a operation name in the configuration.

<hornetq:binding.hornetq>
    <swyd:operationSelector operationName="greet" xmlns:swyd="urn:switchyard-config:switchyard:1.0"/>
(... snip ...)
</hornetq:binding.hornetq>

XPath Operation Selector

specify a XPath location which contains a operation name to be invoked in the message contents.

If the configuration looks like this:

<jca:binding.jca>
    <swyd:operationSelector.xpath expression="//person/language" xmlns:swyd="urn:switchyard-config:switchyard:1.0"/>
(... snip ...)
</jca:binding.jca>

And the message content is like this:

<person>
    <name>Fernando</name>
    <language>spanish</language>
</person>

Then operation spanish() would be invoked.

Regex Operation Selector

specify a Regular Expression to find a operation name to be invoked in the message contents.

If the configuration looks like this:

<http:binding.http>
    <swyd:operationSelector.regex expression="[a-zA-Z]*Operation" xmlns:swyd="urn:switchyard-config:switchyard:1.0"/>
(... snip ...)
</http:binding.http>

And the message content is like this:

xxx yyy zzz regexOperation aaa bbb ccc

Then operation regexOperation() would be invoked.

Java Operation Selector

specify a Java class which is able to determine the operation to be invoked.

configuration should look like this:

<jca:binding.jca>
    <swyd:operationSelector.java class="org.switchyard.example.MyOperationSelectorImpl" xmlns:swyd="urn:switchyard-config:switchyard:1.0"/>
(... snip ...)
</jca:binding.jca>

Note that the org.switchyard.example.MyOperationSelectorImpl needs to be a subclass of org.switchyard.component.common.selector.OperationSelector or other concrete OperationSelector classes for each service bindings. You can override the selectOperation() method as you like.

Default OperationSelector implementation for each service bindings are following:

• Camel : org.switchyard.component.camel.selector.CamelOperationSelector

• JCA/JMS : org.switchyard.component.jca.selector.JMSOperationSelector

• JCA/CCI : org.switchyard.component.jca.selector.CCIOperationSelector

• HTTP : org.switchyard.component.http.selector.HttpOperationSelector

Scope of Support

Support for operation selector is limited to Camel, JCA and HTTP service bindings. Support for other service bindings will be added in the future.

Content Type Names

Since transformations occur between named types (i.e. from type A, to type B), it's important to understand how the type names are derived.  The type of the message is determined based on the service contract, which can be WSDL or Java.

For WSDL interfaces, the message name is determined based on the fully-qualified element name of a WSDL message.  Take the following WSDL definition:

<definitions xmlns:tns="urn:switchyard-quickstart:bean-service:1.0">  
  <message name="submitOrder">
    <part name="parameters" element="tns:submitOrder"/>
  </message>
  <portType name="OrderService">
    <operation name="submitOrder">
      <input message="tns:submitOrder"/>
    </operation>
  </portType>
</definitions>

This would yield the following message type name based on the message element name defined in the WSDL:

{urn:switchyard-quickstart:bean-service:1.0}submitOrder

When Java interfaces are used for the service contract, the message name consists of the full package name + the class name, prefixed with "java:".

package org.switchyard.example;
public interface OrderService {
    void submitOrder(Order order);
}

The message type name for the submitOrder method in this Java interface would be "java:org.switchyard.example.Order".  Occasionally, it can be useful to override the default operation name generated for a Java interface.  The @OperationTypes annotation provides this capability by allowing the user to specify the input, output, and/or fault type names used for a Java service interface.  For example, if we wanted to accept XML input content without any need for transformation to a Java object model, the OrderService interface could be changed to look like this:

package org.switchyard.example;
@OperationTypes(in = "{urn:switchyard-quickstart:bean-service:1.0}submitOrder")
public interface OrderService {
    void submitOrder(String orderXML);
}

Aside from short-circuiting the requirement for transformation, this annotation can be useful if you want to maintain tight control over the names used for message content.

JAXB Java Model Creation

JAXB Java models can be generated from an XML Schema using XJC, or from a WSDL using tools like wsconsume (.sh/.bat), which is shipped with both SwitchYard AS6 and AS7 distros (in the bin directory).

JAXB Transformer Configurations

Working out the available transformations is quite simple. Just look in the ObjectFactory class source file (ObjectFactory.java). In this source file you will see factory methods representing the available marshallings/unmarshallings e.g.

@XmlElementDecl(namespace = "http://com.acme/orders", name = "create")
public JAXBElement<CreateOrder> createOrder(CreateOrder value) {
    return new JAXBElement<Order>(_CreateOrder_QNAME, CreateOrder.class, null, value);
}

In the above example, the @XmlElementDecl annotation tells us that the XML QName associated with the com.acme.orders.CreateOrder type is "{http://com.acme/orders}create". From this, we can deduce that we have the following possible SwitchYard JAXB Transformer configurations:

<transform.jaxb from="{http://com.acme/orders}create" to="java:com.acme.orders.CreateOrder" />
<transform.jaxb from="java:com.acme.orders.CreateOrder" to="{http://com.acme/orders}create" />

Automatically Detected JAXB Transformations

One of the nice things about the JAXB Transformer integrations in SwitchYard is the fact that JAXB Transformations are automatically detected and automatically added, for your application deployment. So, if for example, you develop a CDI Bean Service and use JAXB generated types in the Service Interface, you will not need to configure any of the transformations. SwitchYard will automatically detect their availability for your application and will automatically apply them at the appropriate time during service invocation.

Content Type Names

Since validations occur with named type (i.e. type A) as well as transformations, it's important to understand how the type names are derived.   Please refer to the Content Type Names section in the Transformation chapter if you have not ever seen it.

ValidationResult

ValidationResult is a simple interface which represents the result of validation. It has 2 methods, isValid() and getDetail(). isValid() returns whether the validation succeeded or not. _getDetail() returns error message if validation failed.

package org.switchyard.validate;
public interface ValidationResult {
    boolean isValid();
    String getDetail();
}

There are 3 convenience methods on org.switchyard.validate.BaseValidator, validResult(), invalidResult(), and invalidResult(String) which help you to generate ValidationResult object.

XML Catalog

You can use XML catalog to decouple the schema file location from schema definition itself. This schema is orders.xsd which has a import element. It refers to logical name orders.base by the schemaLocation attribute:

<schema xmlns="http://www.w3.org/2001/XMLSchema"
        targetNamespace="urn:switchyard-quickstart:validate-xml:0.1.0"
        xmlns:base="urn:switchyard-quickstart:validate-xml-base:0.1.0"
        xmlns:orders="urn:switchyard-quickstart:validate-xml:0.1.0">
        <import namespace="urn:switchyard-quickstart:validate-xml-base:0.1.0" schemaLocation="orders.base"/>
...

And this is the catalog.xml which resolves actual schema location from logical name orders.base:

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    <system systemId="orders.base" uri="orders-base.xsd"/>
</catalog>

SwitchYardRunner and SwitchYardTestKit

To take advantage of the test support in SwitchYard, your unit test should be annotated with the SwitchYardRunner JUnit test Runner class. SwitchYardRunner takes care of creating and starting an embedded runtime for each test method. After the embedded runtime is started, the project containing the test is packaged as a SwitchYard application and deployed to it. The runtime state of the deployed SwitchYard test application is represented by an instance of the SwitchYardTestKit class, which is injected into the test when a property of type SwitchYardTestKit is declared in the test.

@RunWith(SwitchYardRunner.class)
public class MyServiceTest  {

    private SwitchYardTestKit testKit;

    @Test   
    public void testOperation() {
        MyTestServiceHandler service = new MyTestServiceHandler();

        // register the service...
        testKit.registerInOutService("MyService", service);
       
        // invoke the service and capture the response...
        Message response = newInvoker("MyService")
        .sendInOut("<create>A1234</create>");

        // test the response content by doing an XML comparison with a
        // file resource on the classpath...
        testKit.compareXMLToResource(response.getContent(String.class), "/myservice/expected-create-response.xml");
    }

    private class MyTestServiceHandler implements ExchangeHandler {
        // implement methods....
    }
}

The SwitchYardTestKit provides a set of utility methods for performing all sorts of deployment configuration and test operations.

SwitchYardTestCaseConfig

The optional SwitchYardTestCaseConfig annotation can be used control the behavior of the SwitchYardRunner:

• config: allows the specification of a SwitchYard XML configuration file (switchyard.xml) for the test. The SwitchYardRunner will attempt to load the specified configuration from the classpath. If if fails to locate the config on the classpath, it will then attempt to locate it on the file system (e.g. within the project structure).

• mixins: composition-based method for adding specific testing tools to your test case.  Each TestMixIn provides customized testing tools for things like service implementations, gateway bindings, and transformers. When a TestMixIn is annotated on a Test Class, the SwitchYardRunner handles all the initialization and cleanup (lifecycle) of the TestMixIn instance(s). It's also possible to manually create and manage TestMixIn instance(s) within your test class if (for example) you are not using the SwitchYardRunner.

• scanners: add classpath scanning as part of the test lifecycle. This adds the same Scanner behavior as is available with the SwitchYard maven build plugin, but allows the scanning to take place as part of the test lifecycle. You will often find that you need to add Scanners if you want your test to run inside your IDE. This is because running your test inside your IDE bypasses the whole maven build process, which means the build plugin does not perform any scanning for you.

@RunWith(SwitchYardRunner.class)
@SwitchYardTestCaseConfig(config = "testconfigs/switchyard-01.xml", mixins = {CDIMixIn.class, BPMMixIn.class}, scanners = {BeanSwitchYardScanner.class, TransformSwitchYardScanner.class})
public class MyServiceTest  {

    @Test   
    public void testOperation() {
        newInvoker("OrderService")
        .operation("createOrder")
        .sendInOnly("<order><product>AAA</product><quantity>2</quantity></order>");
    }
}

<dependency>
    <groupId>org.switchyard.components</groupId>
    <artifactId>switchyard-component-test-mixin-name</artifactId>
    <version>release-version</version> <!-- e.g. "0.7.0" -->
    <scope>test</scope>
</dependency>

Metadata and Support Class Injections

As shown above, injecting the SwitchYardTestKit instance into the test at runtime is simply a case of declaring a property of that type in the test class.

@RunWith(SwitchYardRunner.class)
public class MyServiceTest  {

    private SwitchYardTestKit testKit;

    // implement test methods...
}

The SwitchYard test framework also injects other test support and metadata classes, which we outline in the following sections.

@RunWith(SwitchYardRunner.class)
public class MyServiceTest  {

    private Deployment deployment;

    // implement test methods...
}

@RunWith(SwitchYardRunner.class)
public class MyServiceTest  {

    private SwitchYardModel model;

    // implement test methods...
}

@RunWith(SwitchYardRunner.class)
public class MyServiceTest  {

    private ServiceDomain serviceDomain;

    // implement test methods...
}

@RunWith(SwitchYardRunner.class)
public class MyServiceTest  {

    private TransformerRegistry transformRegistry;

    // implement test methods...
}

@RunWith(SwitchYardRunner.class)
@SwitchYardTestCaseConfig(mixins = {CDIMixIn.class, HTTPMixIn.class})
public class MyServiceTest  {

    private CDIMixIn cdiMixIn;
    private HTTPMixIn httpIn;

    // implement test methods...
}

@RunWith(SwitchYardRunner.class)
@SwitchYardTestCaseConfig(mixins = {CDIMixIn.class, PropertyMixIn.class, HTTPMixIn.class})
public class MyServiceTest  {

    private PropertyMixIn propMixIn;
    private HTTPMixIn httpMixIn;

    @BeforeDeploy
    public void setTestProperties() {
        propMixIn.set("soapPort", Integer.valueOf(18002));
    }

    // implement test methods...
}

@RunWith(SwitchYardRunner.class)
@SwitchYardTestCaseConfig(config = "testconfigs/switchyard-01.xml")
public class MyServiceTest  {

    @ServiceOperation("OrderService.createOrder")
    private Invoker createOrderInvoker;

    @Test   
    public void test_createOrder() {
        createOrderInvoker.sendInOnly("<order><product>AAA</product><quantity>2</quantity></order>");
    }
}

@RunWith(SwitchYardRunner.class)
@SwitchYardTestCaseConfig(config = "testconfigs/switchyard-01.xml" exclude="soap")
public class NoSOAPTest  {
   ...
}

@RunWith(SwitchYardRunner.class)
@SwitchYardTestCaseConfig(config = "testconfigs/switchyard-02.xml" include="bean")
public class BeanServicesOnlyTest  {
...
}

@BeforeDeploy
public void before() {
    ResourceAdapterConfig ra = new ResourceAdapterConfig(ResourceAdapterConfig.ResourceAdapterType.HORNETQ);
    _jcaMixIn.deployResourceAdapters(ra);
}

Annotations

The following annotations, enums, interface and class exist in the org.switchyard.serial.graph package:

• @Strategy - Here you can define the serialization strategy, including access type, coverage type, and factory (all optional) for your class.

  • access=AccessType - BEAN (default) for getter/setter property access, FIELD for member variable access.

  • coverage=CoverageType - INCLUSIVE (default) for serializing all properties, EXCLUSIVE for ignoring all properties. (See @Include and @Exclude below for overrides.)

  • factory=Factory - Interface for how the class gets instantiated.

    • DefaultFactory - Creates an instance of the class using the default constructor.

• @Include - Placed on individual getter methods or fields to override CoverageType.EXCLUSIVE.

• @Exclude - Placed on individual getter methods or fields to override CoverageType.INCLUSIVE.